# -*- coding: utf-8 -*-
"""
    xfree.core.auth.activation
    ~~~~~~~~~~~~~~~~~~~~~
    文件描述：处理xfree中账户激活的接口
    作者：xfree
    邮箱：cy_83k@qq.com

"""

from abc import ABC, abstractmethod


class AccountActivator(ABC):
    """
    在需要用户在使用前激活账户的安装中，管理账户激活的接口。
    """

    @abstractmethod
    def initiate_account_activation(self, user):
        """
        此方法是抽象的。

        用于向用户提供激活账户的邀请。
        这可以采取任何形式，但建议采用如电子邮件这样的永久通信形式。

        在为用户创建用于激活账户的令牌时，如果遇到失败（例如，
        用户请求发送令牌的电子邮件未在本安装中注册，或者与该电子邮件关联的账户已被激活），
        则可能会抛出ValidationError异常。

        :param user: 激活请求所涉及的用户。
        :type user: :class:`User<xfree.user.models.User>`
        """
        pass

    @abstractmethod
    def activate_account(self, token):
        """
        此方法是抽象的。

        用于处理账户的实际激活。
        传入的令牌是发送给用户用于激活的序列化令牌。
        如果在解析或使用令牌时遇到失败，则可能会抛出TokenError或ValidationError异常。

        :param str token: 发送给用户的原始序列化令牌
        """
        pass